<!DOCTYPE html><html><head>
<title>pki - public key encryption</title>
<style type="text/css"><!--
    HTML {
	background: 	#FFFFFF;
	color: 		black;
    }
    BODY {
	background: 	#FFFFFF;
	color:	 	black;
    }
    DIV.doctools {
	margin-left:	10%;
	margin-right:	10%;
    }
    DIV.doctools H1,DIV.doctools H2 {
	margin-left:	-5%;
    }
    H1, H2, H3, H4 {
	margin-top: 	1em;
	font-family:	sans-serif;
	font-size:	large;
	color:		#005A9C;
	background: 	transparent;
	text-align:		left;
    }
    H1.doctools_title {
	text-align: center;
    }
    UL,OL {
	margin-right: 0em;
	margin-top: 3pt;
	margin-bottom: 3pt;
    }
    UL LI {
	list-style: disc;
    }
    OL LI {
	list-style: decimal;
    }
    DT {
	padding-top: 	1ex;
    }
    UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
	font:		normal 12pt/14pt sans-serif;
	list-style:	none;
    }
    LI.doctools_section, LI.doctools_subsection {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding: 	0em;
    }
    PRE {
	display: 	block;
	font-family:	monospace;
	white-space:	pre;
	margin:		0%;
	padding-top:	0.5ex;
	padding-bottom:	0.5ex;
	padding-left:	1ex;
	padding-right:	1ex;
	width:		100%;
    }
    PRE.doctools_example {
	color: 		black;
	background: 	#f5dcb3;
	border:		1px solid black;
    }
    UL.doctools_requirements LI, UL.doctools_syntax LI {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding:	0em;
    }
    DIV.doctools_synopsis {
	color: 		black;
	background: 	#80ffff;
	border:		1px solid black;
	font-family:	serif;
	margin-top: 	1em;
	margin-bottom: 	1em;
    }
    UL.doctools_syntax {
	margin-top: 	1em;
	border-top:	1px solid black;
    }
    UL.doctools_requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<!-- Generated from file 'pki.man' by tcllib/doctools with format 'html'
   -->
<!-- Copyright &amp;copy; 2010, 2011, 2012, 2013, Roy Keene, Andreas Kupries
   -->
<!-- pki.n
   -->
<body><hr> [
   <a href="../../../../../../../../home">Tcllib Home</a>
&#124; <a href="../../../../toc.html">Main Table Of Contents</a>
&#124; <a href="../../../toc.html">Table Of Contents</a>
&#124; <a href="../../../../index.html">Keyword Index</a>
&#124; <a href="../../../../toc0.html">Categories</a>
&#124; <a href="../../../../toc1.html">Modules</a>
&#124; <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<div class="doctools">
<h1 class="doctools_title">pki(n) 0.10 tcllib &quot;public key encryption&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pki - Implementation of the public key cipher</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section4">REFERENCES</a></li>
<li class="doctools_section"><a href="#section5">AUTHORS</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pki <span class="opt">?0.10?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pki::encrypt</b> <span class="opt">?<i class="arg">-binary</i>?</span> <span class="opt">?<i class="arg">-hex</i>?</span> <span class="opt">?<i class="arg">-pad</i>?</span> <span class="opt">?<i class="arg">-nopad</i>?</span> <span class="opt">?<i class="arg">-priv</i>?</span> <span class="opt">?<i class="arg">-pub</i>?</span> <span class="opt">?<i class="arg">--</i>?</span> <i class="arg">input</i> <i class="arg">key</i></a></li>
<li><a href="#2"><b class="cmd">::pki::decrypt</b> <span class="opt">?<i class="arg">-binary</i>?</span> <span class="opt">?<i class="arg">-hex</i>?</span> <span class="opt">?<i class="arg">-unpad</i>?</span> <span class="opt">?<i class="arg">-nounpad</i>?</span> <span class="opt">?<i class="arg">-priv</i>?</span> <span class="opt">?<i class="arg">-pub</i>?</span> <span class="opt">?<i class="arg">--</i>?</span> <i class="arg">input</i> <i class="arg">key</i></a></li>
<li><a href="#3"><b class="cmd">::pki::sign</b> <i class="arg">input</i> <i class="arg">key</i> <span class="opt">?<i class="arg">algo</i>?</span></a></li>
<li><a href="#4"><b class="cmd">::pki::verify</b> <i class="arg">signedmessage</i> <i class="arg">plaintext</i> <i class="arg">key</i> <span class="opt">?<i class="arg">algo</i>?</span></a></li>
<li><a href="#5"><b class="cmd">::pki::key</b> <i class="arg">key</i> <span class="opt">?<i class="arg">password</i>?</span> <span class="opt">?<i class="arg">encodePem</i>?</span></a></li>
<li><a href="#6"><b class="cmd">::pki::pkcs::parse_key</b> <i class="arg">key</i> <span class="opt">?<i class="arg">password</i>?</span></a></li>
<li><a href="#7"><b class="cmd">::pki::x509::parse_cert</b> <i class="arg">cert</i></a></li>
<li><a href="#8"><b class="cmd">::pki::rsa::generate</b> <i class="arg">bitlength</i> <span class="opt">?<i class="arg">exponent</i>?</span></a></li>
<li><a href="#9"><b class="cmd">::pki::x509::verify_cert</b> <i class="arg">cert</i> <i class="arg">trustedcerts</i> <span class="opt">?<i class="arg">intermediatecerts</i>?</span></a></li>
<li><a href="#10"><b class="cmd">::pki::x509::validate_cert</b> <i class="arg">cert</i> <span class="opt">?<b class="option">-sign_message</b> <i class="arg">dn_of_signer</i>?</span> <span class="opt">?<b class="option">-encrypt_message</b> <i class="arg">dn_of_signer</i>?</span> <span class="opt">?<b class="option">-sign_cert</b> <i class="arg">dn_to_be_signed</i> <i class="arg">ca_depth</i>?</span> <span class="opt">?<b class="option">-ssl</b> <i class="arg">dn</i>?</span></a></li>
<li><a href="#11"><b class="cmd">::pki::pkcs::create_csr</b> <i class="arg">keylist</i> <i class="arg">namelist</i> <span class="opt">?<i class="arg">encodePem</i>?</span> <span class="opt">?<i class="arg">algo</i>?</span></a></li>
<li><a href="#12"><b class="cmd">::pki::pkcs::parse_csr</b> <i class="arg">csr</i></a></li>
<li><a href="#13"><b class="cmd">::pki::x509::create_cert</b> <i class="arg">signreqlist</i> <i class="arg">cakeylist</i> <i class="arg">serial_number</i> <i class="arg">notBefore</i> <i class="arg">notAfter</i> <i class="arg">isCA</i> <i class="arg">extensions</i> <span class="opt">?<i class="arg">encodePem</i>?</span> <span class="opt">?<i class="arg">algo</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pki::encrypt</b> <span class="opt">?<i class="arg">-binary</i>?</span> <span class="opt">?<i class="arg">-hex</i>?</span> <span class="opt">?<i class="arg">-pad</i>?</span> <span class="opt">?<i class="arg">-nopad</i>?</span> <span class="opt">?<i class="arg">-priv</i>?</span> <span class="opt">?<i class="arg">-pub</i>?</span> <span class="opt">?<i class="arg">--</i>?</span> <i class="arg">input</i> <i class="arg">key</i></a></dt>
<dd><p>Encrypt a message using PKI (probably RSA).
Requires the caller to specify either <b class="option">-priv</b> to encrypt with
the private key or <b class="option">-pub</b> to encrypt with the public key.  The
default option is to pad and return in hex.  One of <b class="option">-pub</b> or
<b class="option">-priv</b> must be specified.
The <b class="option">-hex</b> option causes the data to be returned in encoded as
a hexidecimal string, while the <b class="option">-binary</b> option causes the data
to be returned as a binary string.  If they are specified multiple
times, the last one specified is used.
The <b class="option">-pad</b> option causes the data to be padded per PKCS#1 prior
to being encrypted.  The <b class="option">-nopad</b> inhibits this behaviour.  If
they are specified multiple times, the last one specified is used.
The input to encrypt is specified as <i class="arg">input</i>.
The <i class="arg">key</i> parameter, holding the key to use, is a return value
from either
<b class="cmd">::pki::pkcs::parse_key</b>,
<b class="cmd">::pki::x509::parse_cert</b>, or
<b class="cmd">::pki::rsa::generate</b>.</p>
<p>Mapping to OpenSSL's <b class="syscmd">openssl</b> application:</p>
<ol class="doctools_enumerated">
<li><p>&quot;openssl rsautl -encrypt&quot; == &quot;::pki::encrypt -binary -pub&quot;</p></li>
<li><p>&quot;openssl rsautl -sign&quot;    == &quot;::pki::encrypt -binary -priv&quot;</p></li>
</ol></dd>
<dt><a name="2"><b class="cmd">::pki::decrypt</b> <span class="opt">?<i class="arg">-binary</i>?</span> <span class="opt">?<i class="arg">-hex</i>?</span> <span class="opt">?<i class="arg">-unpad</i>?</span> <span class="opt">?<i class="arg">-nounpad</i>?</span> <span class="opt">?<i class="arg">-priv</i>?</span> <span class="opt">?<i class="arg">-pub</i>?</span> <span class="opt">?<i class="arg">--</i>?</span> <i class="arg">input</i> <i class="arg">key</i></a></dt>
<dd><p>Decrypt a message using PKI (probably RSA). See <b class="cmd">::pki::encrypt</b> for option handling.</p>
<p>Mapping to OpenSSL's <b class="syscmd">openssl</b> application:</p>
<ol class="doctools_enumerated">
<li><p>&quot;openssl rsautl -decrypt&quot; == &quot;::pki::decrypt -binary -priv&quot;</p></li>
<li><p>&quot;openssl rsautl -verify&quot;  == &quot;::pki::decrypt -binary -pub&quot;</p></li>
</ol></dd>
<dt><a name="3"><b class="cmd">::pki::sign</b> <i class="arg">input</i> <i class="arg">key</i> <span class="opt">?<i class="arg">algo</i>?</span></a></dt>
<dd><p>Digitally sign message <i class="arg">input</i> using the private <i class="arg">key</i>.</p>
<p>If <i class="arg">algo</i> is ommited &quot;sha1&quot; is assumed. Possible values for
<i class="arg">algo</i> include &quot;<b class="const">md5</b>&quot;, &quot;<b class="const">sha1</b>&quot;, &quot;<b class="const">sha256</b>&quot;,
and &quot;<b class="const">raw</b>&quot;.</p>
<p>Specifying &quot;<b class="const">raw</b>&quot; for <i class="arg">algo</i> will inhibit the
building of an ASN.1 structure to encode which hashing algorithm was
chosen.
<em>Attention</em>: In this case the corresponding <b class="cmd">pkgi::verify</b>
must be called <b class="const">with</b> algorithm information.
Conversely, specifying a non-&quot;<b class="const">raw</b>&quot; algorithm here means that
the corresponding <b class="cmd">pkgi::verify</b> invokation has to be made
<em>without</em> algorithm information.</p>
<p>The <i class="arg">input</i> should be the plain text, hashing will be
performed on it.</p>
<p>The <i class="arg">key</i> should include the private key.</p></dd>
<dt><a name="4"><b class="cmd">::pki::verify</b> <i class="arg">signedmessage</i> <i class="arg">plaintext</i> <i class="arg">key</i> <span class="opt">?<i class="arg">algo</i>?</span></a></dt>
<dd><p>Verify a digital signature using a public <i class="arg">key</i>.  Returns true or false.</p>
<p><em>Attention</em>: The algorithm information <i class="arg">algo</i> has to
be specified if and only if the <b class="cmd">pki::sign</b> which generated the
<i class="arg">signedmessage</i> was called with algorithm &quot;<b class="const">raw</b>&quot;. This
inhibited the building of the ASN.1 structure encoding the chosen
hashing algorithm. Conversely, if a proper algorithm was specified
during signing then you <em>must not</em> specify an algorithm here.</p></dd>
<dt><a name="5"><b class="cmd">::pki::key</b> <i class="arg">key</i> <span class="opt">?<i class="arg">password</i>?</span> <span class="opt">?<i class="arg">encodePem</i>?</span></a></dt>
<dd><p>Convert a key structure into a serialized PEM (default) or DER encoded private key suitable for other applications.  For RSA keys this means PKCS#1.</p></dd>
<dt><a name="6"><b class="cmd">::pki::pkcs::parse_key</b> <i class="arg">key</i> <span class="opt">?<i class="arg">password</i>?</span></a></dt>
<dd><p>Convert a PKCS#1 private <i class="arg">key</i> into a usable key, i.e. one which
can be used as argument for
<b class="cmd">::pki::encrypt</b>,
<b class="cmd">::pki::decrypt</b>,
<b class="cmd">::pki::sign</b>, and
<b class="cmd">::pki::verify</b>.</p></dd>
<dt><a name="7"><b class="cmd">::pki::x509::parse_cert</b> <i class="arg">cert</i></a></dt>
<dd><p>Convert an X.509 certificate to a usable (public) key, i.e. one which
can be used as argument for
<b class="cmd">::pki:encrypt</b>,
<b class="cmd">::pki::decrypt</b>, and
<b class="cmd">::pki::verify</b>.
The <i class="arg">cert</i> argument can be either PEM or DER encoded.</p></dd>
<dt><a name="8"><b class="cmd">::pki::rsa::generate</b> <i class="arg">bitlength</i> <span class="opt">?<i class="arg">exponent</i>?</span></a></dt>
<dd><p>Generate a new RSA key pair, the parts of which can be used as
argument for
<b class="cmd">::pki::encrypt</b>,
<b class="cmd">::pki::decrypt</b>,
<b class="cmd">::pki::sign</b>, and
<b class="cmd">::pki::verify</b>.
The <i class="arg">bitlength</i> argument is the length of the public key modulus.
The <i class="arg">exponent</i> argument should generally not be specified unless
you really know what you are doing.</p></dd>
<dt><a name="9"><b class="cmd">::pki::x509::verify_cert</b> <i class="arg">cert</i> <i class="arg">trustedcerts</i> <span class="opt">?<i class="arg">intermediatecerts</i>?</span></a></dt>
<dd><p>Verify that a trust can be found between the certificate specified in the
<i class="arg">cert</i> argument and one of the certificates specified in the list
of certificates in the <i class="arg">trustedcerts</i> argument.  (Eventually the
chain can be through untrusted certificates listed in the <i class="arg">intermediatecerts</i>
argument, but this is currently unimplemented).
The certificates specified in the <i class="arg">cert</i> and <i class="arg">trustedcerts</i> option
should be parsed (from <b class="cmd">::pki::x509::parse_cert</b>).</p></dd>
<dt><a name="10"><b class="cmd">::pki::x509::validate_cert</b> <i class="arg">cert</i> <span class="opt">?<b class="option">-sign_message</b> <i class="arg">dn_of_signer</i>?</span> <span class="opt">?<b class="option">-encrypt_message</b> <i class="arg">dn_of_signer</i>?</span> <span class="opt">?<b class="option">-sign_cert</b> <i class="arg">dn_to_be_signed</i> <i class="arg">ca_depth</i>?</span> <span class="opt">?<b class="option">-ssl</b> <i class="arg">dn</i>?</span></a></dt>
<dd><p>Validate that a certificate is valid to be used in some capacity.  If
multiple options are specified they must all be met for this procedure
to return &quot;true&quot;.
Currently, only the <b class="option">-sign_cert</b> option is functional.
Arguments for the <b class="option">-sign_cert</b> option are <i class="arg">dn_to_be_signed</i>
and <i class="arg">ca_depth</i>.  The <i class="arg">dn_to_be_signed</i> is the distinguished from
the subject of a certificate to verify that the certificate specified in
the <i class="arg">cert</i> argument can sign.  The <i class="arg">ca_depth</i> argument is used to
indicate at which depth the verification should be done at.  Some
certificates are limited to how far down the chain they can be used to
verify a given certificate.</p></dd>
<dt><a name="11"><b class="cmd">::pki::pkcs::create_csr</b> <i class="arg">keylist</i> <i class="arg">namelist</i> <span class="opt">?<i class="arg">encodePem</i>?</span> <span class="opt">?<i class="arg">algo</i>?</span></a></dt>
<dd><p>Generate a certificate signing request from a key pair specified in
the <i class="arg">keylist</i> argument.
The <i class="arg">namelist</i> argument is a list of &quot;name&quot; followed by &quot;value&quot;
pairs to encoding as the requested distinguished name in the CSR.
The <i class="arg">encodePem</i> option specifies whether or not the result should
be PEM encoded or DER encoded.  A &quot;true&quot; value results in the result
being PEM encoded, while any other value 9results in the the result
being DER encoded.  DER encoding is the default.
The <i class="arg">algo</i> argument specifies the hashing algorithm we should use
to sign this certificate signing request with.  The default is &quot;sha1&quot;.
Other possible values include &quot;md5&quot; and &quot;sha256&quot;.</p></dd>
<dt><a name="12"><b class="cmd">::pki::pkcs::parse_csr</b> <i class="arg">csr</i></a></dt>
<dd><p>Parse a Certificate Signing Request.  The <i class="arg">csr</i> argument can be
either PEM or DER encoded.</p></dd>
<dt><a name="13"><b class="cmd">::pki::x509::create_cert</b> <i class="arg">signreqlist</i> <i class="arg">cakeylist</i> <i class="arg">serial_number</i> <i class="arg">notBefore</i> <i class="arg">notAfter</i> <i class="arg">isCA</i> <i class="arg">extensions</i> <span class="opt">?<i class="arg">encodePem</i>?</span> <span class="opt">?<i class="arg">algo</i>?</span></a></dt>
<dd><p>Sign a signing request (usually from <b class="cmd">::pki::pkcs::create_csr</b> or
<b class="cmd">::pki::pkcs::parse_csr</b>) with a Certificate Authority (CA) certificate.
The <i class="arg">signreqlist</i> argument should be the parsed signing request.
The <i class="arg">cakeylist</i> argument should be the parsed CA certificate.
The <i class="arg">serial_number</i> argument should be a serial number unique to
this certificate from this certificate authority.
The <i class="arg">notBefore</i> and <i class="arg">notAfter</i> arguments should contain the
time before and after which (respectively) the certificate should
be considered invalid.  The time should be encoded as something
<b class="cmd">clock format</b> will accept (i.e., the results of <b class="cmd">clock seconds</b>
and <b class="cmd">clock add</b>).
The <i class="arg">isCA</i> argument is a boolean argumen describing whether or not
the signed certificate should be a a CA certificate.  If specified as
true the &quot;id-ce-basicConstraints&quot; extension is added with the arguments
of &quot;critical&quot; being true, &quot;allowCA&quot; being true, and caDepth being
-1 (infinite).
The <i class="arg">extensions</i> argument is a list of extensions and their parameters
that should be encoded into the created certificate.   Currently only one
extension is understood (&quot;id-ce-basicConstraints&quot;).  It accepts three
arguments <i class="arg">critical</i> <i class="arg">allowCA</i> <i class="arg">caDepth</i>.  The <i class="arg">critical</i>
argument to this extension (and any extension) whether or not the
validator should reject the certificate as invalid if it does not
understand the extension (if set to &quot;true&quot;) or should ignore the extension
(if set to &quot;false&quot;).  The <i class="arg">allowCA</i> argument is used to specify
as a boolean value whether or not we can be used a certificate
authority (CA).  The <i class="arg">caDepth</i> argument indicates how many children
CAs can be children of this CA in a depth-wise fashion.  A value of &quot;0&quot;
for the <i class="arg">caDepth</i> argument means that this CA cannot sign a CA
certificate and have the result be valid.  A value of &quot;-1&quot; indicates
infinite depth.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
<pre class="doctools_example">
</pre>
<pre class="doctools_example">
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li></li>
</ol>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">AUTHORS</a></h2>
<p>Roy Keene</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>rsa</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../aes/aes.html">aes(n)</a>, <a href="../blowfish/blowfish.html">blowfish(n)</a>, <a href="../des/des.html">des(n)</a>, <a href="../md5/md5.html">md5(n)</a>, <a href="../sha1/sha1.html">sha1(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#cipher">cipher</a>, <a href="../../../../index.html#data_integrity">data integrity</a>, <a href="../../../../index.html#encryption">encryption</a>, <a href="../../../../index.html#public_key_cipher">public key cipher</a>, <a href="../../../../index.html#rsa">rsa</a>, <a href="../../../../index.html#security">security</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Hashes, checksums, and encryption</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright &copy; 2010, 2011, 2012, 2013, Roy Keene, Andreas Kupries</p>
</div>
</div></body></html>
